#ifndef _YPROPERTIESFILE_H
#define _YPROPERTIESFILE_H
#include <tool/ydefine.h>
#include <tool/ystr.h>

/** Function pointers struct, use externally */
typedef struct propertiesFile *propertiesFile;
/** Data struct, use internally */
typedef struct propertiesFileData *propertiesFileData;

/** struct of properties file function pointers */
struct propertiesFile {
  /*--- data ---*/
  propertiesFileData d;
  /*--- function pointers ---*/
  /** Free a <code>propertiesFile</code>, free up the memory.
  @param objP pass in the address of <code>propertiesFile</code> to be free.
  @return <code>true</code> if successfully otherwise <code>false</code>.
  */
  boolean (*free)(propertiesFile *objP);
  /* specific operation */
  /** Return a cloned string of the file name & path 
  that this <code>propertiesFile</code> is working with.
  <p>Since this string is <code>malloc(..)</code>, to avoid memory leak
  it should be freed when no longer needed with a call to 
  <code>free(void *)</code>.
  </p>
  @param obj pass in the <code>propertiesFile</code>.
  @return Return a cloned string of the file name & path that 
    this <code>propertiesFile</code> is working with
    or <code>NULL</code> if failure.
  */
  char *(*getFilename)(const propertiesFile obj);
  /** Returns a list of the keys in this <code>propertiesFile</code>.
  <p>Since this <code>char **</code>, a 2D array is 
  <code>malloc(..)</code>, to avoid memory leak
  it should be freed when no longer needed with a call to 
  <code>free(void *)</code>.
  </p>
  @param obj pass in the <code>propertiesFile</code>.
  @param numKeys the number of keys in this <code>propertiesFile</code>
  @return Returns a list of the keys in this <code>propertiesFile</code>,
    or <code>NULL</code> if failure.
  */
  char **(*getKeys)(const propertiesFile obj, unsigned int *numKeys);
  /** Gets a string for the given key from this <code>propertiesFile</code>.
  <p>Since this string is <code>malloc(..)</code>, to avoid memory leak
  it should be freed when no longer needed with a call to 
  <code>free(void *)</code>.
  </p>
  @param obj pass in the <code>propertiesFile</code>.
  @param key the key to search for.
  @return Return a cloned string for the given key 
    from this <code>propertiesFile</code> or <code>NULL</code> if failure.
  */
  char *(*getString)(propertiesFile obj, char *key);
  /** Gets a list of string for the given key from 
  this <code>propertiesFile</code>.
  <p>Since this <code>char **</code>, a 2D array is 
  <code>malloc(..)</code>, to avoid memory leak
  it should be freed when no longer needed with a call to 
  <code>free(void *)</code>.
  </p>
  @param obj pass in the <code>propertiesFile</code>.
  @param key the key to search for.
  @param len the length of the list of string that is returned.
  @return Return a cloned string for the given key 
    from this <code>propertiesFile</code> or <code>NULL</code> if failure.
  */
  char **(*getStringArray)(propertiesFile obj, 
      char *key, unsigned int *len);
  /** Gets a string for the given key from this <code>propertiesFile</code>, 
  translate any valid C escape characters into their proper char.
  <p>Since this string is <code>malloc(..)</code>, to avoid memory leak
  it should be freed when no longer needed with a call to 
  <code>free(void *)</code>.
  </p>
  @param obj pass in the <code>propertiesFile</code>.
  @param key the key to search for.
  @return Return a cloned string for the given key 
    from this <code>propertiesFile</code> or <code>NULL</code> if failure.
  */
  char *(*getStringES)(propertiesFile obj, char *key);
  /** Gets a list of string for the given key from 
  this <code>propertiesFile</code>, 
  translate any valid C escape characters into their proper char.
  <p>Since this <code>char **</code>, a 2D array is 
  <code>malloc(..)</code>, to avoid memory leak
  it should be freed when no longer needed with a call to 
  <code>free(void *)</code>.
  </p>
  @param obj pass in the <code>propertiesFile</code>.
  @param key the key to search for.
  @param len the length of the list of string that is returned.
  @return Return a cloned string for the given key 
    from this <code>propertiesFile</code> or <code>NULL</code> if failure.
  */
  char **(*getStringArrayES)(propertiesFile obj, 
      char *key, unsigned int *len);
};

/** Create a properties file struct and 
provide function to access properties file content.
@param file the file to work with.
  MUST provide the relative path or the absolute path to the file and 
  its' full name.
@return a working newly created properties file struct 
  or <code>NULL</code> if failure.
*/
propertiesFile ypropertiesFile_create(char *file);
/** Create a properties file struct and 
provide function to access properties file content.
<code>propertiesFile</code> will NOT free the memory of 
<code>strFn</code> that is created externally, 
you MUST free this yourself.
@param file the file to work with.
  MUST provide the relative path or the absolute path to the file and 
  its' full name.
@param strFn pass in the <code>strFn</code> to use.
@return a working newly created properties file struct 
  or <code>NULL</code> if failure.
*/
propertiesFile ypropertiesFile_createWith(char *file, strFn strFn);

#endif /* _YPROPERTIESFILE_H */
